home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 July: Mac OS SDK / Dev.CD Jul 00 SDK2.toast / Development Kits / Cross Platform / QuickTime 4.1.2 Windows SDK / CIncludes / Translation.h < prev    next >
Encoding:
C/C++ Source or Header  |  2000-04-12  |  12.7 KB  |  349 lines  |  [TEXT/R*ch]
  1. /*
  2.      File:        Translation.h
  3.  
  4.      Contains:    Translation Manager (Macintosh Easy Open) Interfaces.
  5.  
  6.      Version:    Technology:    Macintosh Easy Open 1.1
  7.                  Release:    QuickTime 4.1
  8.  
  9.      Copyright:    (c) 1991-1999 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        For bug reports, consult the following page on
  12.                  the World Wide Web:
  13.  
  14.                      http://developer.apple.com/bugreporter/
  15.  
  16. */
  17. #ifndef __TRANSLATION__
  18. #define __TRANSLATION__
  19.  
  20. #ifndef __MACTYPES__
  21.     #include <MacTypes.h>
  22. #endif
  23.  
  24. #ifndef __FILES__
  25.     #include <Files.h>
  26. #endif
  27.  
  28. #ifndef __COMPONENTS__
  29.     #include <Components.h>
  30. #endif
  31.  
  32. #ifndef __TRANSLATIONEXTENSIONS__
  33.     #include <TranslationExtensions.h>
  34. #endif
  35.  
  36.  
  37.  
  38.  
  39. #if PRAGMA_ONCE
  40. #pragma once
  41. #endif
  42.  
  43. #ifdef __cplusplus
  44. extern "C" {
  45. #endif
  46.  
  47. #if PRAGMA_IMPORT
  48. #pragma import on
  49. #endif
  50.  
  51. #if PRAGMA_STRUCT_ALIGN
  52.     #pragma options align=mac68k
  53. #elif PRAGMA_STRUCT_PACKPUSH
  54.     #pragma pack(push, 2)
  55. #elif PRAGMA_STRUCT_PACK
  56.     #pragma pack(2)
  57. #endif
  58.  
  59. /* enumerated types on how a document can be opened*/
  60. typedef short                             DocOpenMethod;
  61. enum {
  62.     domCannot                    = 0,
  63.     domNative                    = 1,
  64.     domTranslateFirst            = 2,
  65.     domWildcard                    = 3
  66. };
  67.  
  68. /* 0L terminated array of OSTypes, or FileTypes*/
  69. typedef OSType                             TypesBlock[64];
  70. typedef OSType *                        TypesBlockPtr;
  71. /* Progress dialog resource ID*/
  72. enum {
  73.     kTranslationScrapProgressDialogID = -16555
  74. };
  75.  
  76. /* block of data that describes how to translate*/
  77.  
  78. struct FileTranslationSpec {
  79.     OSType                             componentSignature;
  80.     const void *                    translationSystemInfo;
  81.     FileTypeSpec                     src;
  82.     FileTypeSpec                     dst;
  83. };
  84. typedef struct FileTranslationSpec        FileTranslationSpec;
  85. typedef FileTranslationSpec *            FileTranslationSpecArrayPtr;
  86. typedef FileTranslationSpecArrayPtr *    FileTranslationSpecArrayHandle;
  87.  
  88. /*****************************************************************************************
  89. * 
  90. *   GetFileTypesThatAppCanNativelyOpen
  91. * 
  92. *  This routine returns a list of all FileTypes that an application can open by itself
  93. * 
  94. *  Enter:    appVRefNumHint        volume where application resides (can be wrong, and if is, will be used as a starting point)
  95. *             appSignature        signature (creator) of application
  96. *             nativeTypes            pointer to a buffer to be filled with up to 64 FileTypes
  97. * 
  98. *  Exit:    nativeTypes            zero terminated array of FileTypes that can be opened by app
  99. */
  100. EXTERN_API( OSErr )
  101. GetFileTypesThatAppCanNativelyOpen (short                 appVRefNumHint,
  102.                                  OSType                 appSignature,
  103.                                  FileType *                nativeTypes)                        TWOWORDINLINE(0x701C, 0xABFC);
  104.  
  105. /*****************************************************************************************
  106. * 
  107. *  ExtendFileTypeList
  108. * 
  109. *  This routine makes a new list of file types that can be translated into a type in the given list
  110. *  Used by StandardFile
  111. * 
  112. *  Enter:    originalTypeList        pointer to list of file types that can be opened
  113. *             numberOriginalTypes        number of file types in orgTypeList
  114. *              extendedTypeList        pointer to a buffer to be filled with file types
  115. *             numberExtendedTypes        max number of file types that can be put in extendedTypeList
  116. * 
  117. *  Exit:    extendedTypeList        buffer filled in with file types that can be translated
  118. *             numberExtendedTypes        number of file types put in extendedTypeList
  119. */
  120. EXTERN_API( OSErr )
  121. ExtendFileTypeList                (const FileType *        originalTypeList,
  122.                                  short                     numberOriginalTypes,
  123.                                  FileType *                extendedTypeList,
  124.                                  short *                numberExtendedTypes)                TWOWORDINLINE(0x7009, 0xABFC);
  125.  
  126.  
  127. /*****************************************************************************************
  128. * 
  129. * 
  130. *  This routine checks if a file can be opened by a particular application.
  131. *  If so, it returns if it needs to be translated first, and if so then how.
  132. *  The FileTypes that the app can open are specified by nativelyOpenableTypes,
  133. *  or if it is NULL, GetFileTypesThatAppCanNativelyOpen is called.
  134. * 
  135. *  Enter:    targetDocument        document to check if it can be opened
  136. *             appVRefNumHint        vRefNum of application to open doc ( can be wrong, and if is, will be used as a starting point)
  137. *             appSignature        signature (creator) of application to open doc
  138. *             nativeTypes            zero terminated list of FileTypes app can open natively, or NULL to use default list
  139. *             onlyNative            whether to consider if document can be translated before opening
  140. *             howToOpen            pointer to buffer in which to put how the document can be opened
  141. *             howToTranslate        pointer to buffer in which to put a FileTranslationSpec record
  142. * 
  143. *  Exit:    howToOpen            whether file needs to be translated to be read
  144. *             howToTranslate        if file can be translated, buffer filled in with how to translate
  145. *             returns                noErr, noPrefAppErr
  146. */
  147. EXTERN_API( OSErr )
  148. CanDocBeOpened                    (const FSSpec *            targetDocument,
  149.                                  short                     appVRefNumHint,
  150.                                  OSType                 appSignature,
  151.                                  const FileType *        nativeTypes,
  152.                                  Boolean                 onlyNative,
  153.                                  DocOpenMethod *        howToOpen,
  154.                                  FileTranslationSpec *    howToTranslate)                        TWOWORDINLINE(0x701E, 0xABFC);
  155.  
  156.  
  157. /*****************************************************************************************
  158. * 
  159. *  GetFileTranslationPaths
  160. * 
  161. *  This routine returns a list of all ways a translation can occure to or from a FileType.
  162. *  The app is checked to exist.  The hint for each app is the VRefNum and DTRefNum
  163. * 
  164. *  Enter:    srcDoc            source file or NULL for all matches
  165. *             dstDoc            destination FileType or 0 for all matches
  166. *             maxResultCount
  167. *             resultBuffer
  168. *  Exit:    number of paths
  169. */
  170. EXTERN_API( short )
  171. GetFileTranslationPaths            (FSSpec *                srcDocument,
  172.                                  FileType                 dstDocType,
  173.                                  unsigned short         maxResultCount,
  174.                                  FileTranslationSpecArrayPtr  resultBuffer)                    TWOWORDINLINE(0x7038, 0xABFC);
  175.  
  176. /*****************************************************************************************
  177. * 
  178. *  GetPathFromTranslationDialog
  179. * 
  180. *  This routine, with a given document, application, and a passed typelist will display the
  181. *  Macintosh Easy Open translation dialog allowing the user to make a choice.  The choice
  182. *  made will be written as a preference (so the next call to CanDocBeOpened() will work).
  183. *  The routine returns the translation path information.
  184. * 
  185. *  Enter:    theDocument            FSSpec to document to open
  186. *             theApplication        FSSpec to application to open document
  187. *             typeList            Nil terminated list of FileType's (e.g. SFTypeList-like) of types
  188. *                                 you would like the documented translated to.  Order most perferred
  189. *                                 to least.
  190. * 
  191. *  Exit:    howToOpen            Translation method needed to open document
  192. *             howToTranslate        Translation specification
  193. *             returns                Any errors that might occur.
  194. */
  195. EXTERN_API( OSErr )
  196. GetPathFromTranslationDialog    (const FSSpec *            theDocument,
  197.                                  const FSSpec *            theApplication,
  198.                                  TypesBlockPtr             typeList,
  199.                                  DocOpenMethod *        howToOpen,
  200.                                  FileTranslationSpec *    howToTranslate)                        TWOWORDINLINE(0x7037, 0xABFC);
  201.  
  202.  
  203. /*****************************************************************************************
  204. * 
  205. *   TranslateFile
  206. * 
  207. *  This routine reads a file of one format and writes it to another file in another format. 
  208. *  The information on how to translated is generated by the routine CanDocBeOpened.
  209. *  TranslateFile calls through to the TranslateFile Extension's DoTranslateFile routine.  
  210. *  The destination file must not exist.  It is created by this routine.  
  211. * 
  212. *  Enter:    sourceDocument            input file to translate
  213. *             destinationDocument        output file of translation
  214. *             howToTranslate            pointer to info on how to translate
  215. *  Exit:    returns                    noErr, badTranslationSpecErr 
  216. */
  217. EXTERN_API( OSErr )
  218. TranslateFile                    (const FSSpec *            sourceDocument,
  219.                                  const FSSpec *            destinationDocument,
  220.                                  const FileTranslationSpec * howToTranslate)                TWOWORDINLINE(0x700C, 0xABFC);
  221.  
  222. /*****************************************************************************************
  223. * 
  224. *   GetDocumentKindString
  225. * 
  226. *  This routine returns the string the Finder should show for the "kind" of a document
  227. *  in the GetInfo window and in the kind column of a list view.  
  228. * 
  229. *  Enter:    docVRefNum        The volume containing the document
  230. *             docType            The catInfo.fdType of the document
  231. *             docCreator        The catInfo.fdCreator of the document
  232. *             kindString        pointer to where to return the string
  233. * 
  234. *  Exit:    kindString        pascal string.  Ex: "\pSurfCalc spreadsheet"
  235. *             returns            noErr, or afpItemNoFound if kind could not be determined
  236. */
  237. EXTERN_API( OSErr )
  238. GetDocumentKindString            (short                     docVRefNum,
  239.                                  OSType                 docType,
  240.                                  OSType                 docCreator,
  241.                                  Str63                     kindString)                            TWOWORDINLINE(0x7016, 0xABFC);
  242.  
  243. /*****************************************************************************************
  244. * 
  245. *  GetTranslationExtensionName
  246. * 
  247. *  This routine returns the translation system name from a specified TranslationSpec
  248. * 
  249. *  Enter:    translationMethod    The translation path to get the translation name from
  250. * 
  251. *  Exit:    extensionName        The name of the translation system
  252. *             returns                Any errors that might occur
  253. */
  254. EXTERN_API( OSErr )
  255. GetTranslationExtensionName        (const FileTranslationSpec * translationMethod,
  256.                                  Str31                     extensionName)                        TWOWORDINLINE(0x7036, 0xABFC);
  257.  
  258.  
  259. /*****************************************************************************************
  260. * 
  261. *  GetScrapDataProcPtr
  262. * 
  263. *  This is a prototype for the function you must supply to TranslateScrap. It is called to 
  264. *  get the data to be translated.  The first call TranslateScrap will make to this is to
  265. *  ask for the 'fmts' data.  That is a special.   You should resize and fill in the handle
  266. *  with a list all the formats that you have available to be translated, and the length of each.
  267. *  (See I.M. VI 4-23 for details of 'fmts').  It will then be called again asking for one of  
  268. *  the formats that 'fmts' list said was available.
  269. * 
  270. *  Enter:    requestedFormat            Format of data that TranslateScrap needs.
  271. *             dataH                    Handle in which to put the requested data
  272. *             srcDataGetterRefCon        Extra parameter for you passed to TranslateScrap
  273. *             
  274. *  Exit:    dataH                    Handle is resized and filled with data in requested format
  275. */
  276. typedef CALLBACK_API( OSErr , GetScrapDataProcPtr )(ScrapType requestedFormat, Handle dataH, void *srcDataGetterRefCon);
  277. typedef STACK_UPP_TYPE(GetScrapDataProcPtr)                     GetScrapDataUPP;
  278. #if OPAQUE_UPP_TYPES
  279.     EXTERN_API(GetScrapDataUPP)
  280.     NewGetScrapDataUPP               (GetScrapDataProcPtr        userRoutine);
  281.  
  282.     EXTERN_API(void)
  283.     DisposeGetScrapDataUPP           (GetScrapDataUPP            userUPP);
  284.  
  285.     EXTERN_API(OSErr)
  286.     InvokeGetScrapDataUPP           (ScrapType                requestedFormat,
  287.                                     Handle                    dataH,
  288.                                     void *                    srcDataGetterRefCon,
  289.                                     GetScrapDataUPP            userUPP);
  290.  
  291. #else
  292.     enum { uppGetScrapDataProcInfo = 0x00000FE0 };                     /* pascal 2_bytes Func(4_bytes, 4_bytes, 4_bytes) */
  293.     #define NewGetScrapDataUPP(userRoutine)                         (GetScrapDataUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppGetScrapDataProcInfo, GetCurrentArchitecture())
  294.     #define DisposeGetScrapDataUPP(userUPP)                         DisposeRoutineDescriptor(userUPP)
  295.     #define InvokeGetScrapDataUPP(requestedFormat, dataH, srcDataGetterRefCon, userUPP)  (OSErr)CALL_THREE_PARAMETER_UPP((userUPP), uppGetScrapDataProcInfo, (requestedFormat), (dataH), (srcDataGetterRefCon))
  296. #endif
  297. /* support for pre-Carbon UPP routines: NewXXXProc and CallXXXProc */
  298. #define NewGetScrapDataProc(userRoutine)                         NewGetScrapDataUPP(userRoutine)
  299. #define CallGetScrapDataProc(userRoutine, requestedFormat, dataH, srcDataGetterRefCon) InvokeGetScrapDataUPP(requestedFormat, dataH, srcDataGetterRefCon, userRoutine)
  300.  
  301. typedef GetScrapDataUPP                 GetScrapData;
  302. /*****************************************************************************************
  303. * 
  304. *  TranslateScrap
  305. * 
  306. *  This routine resizes the destination handle and fills it with data of the requested format.
  307. *  The data is generated by translated one or more source formats of data supplied by
  308. *  the procedure srcDataGetter.  
  309. *  This routine is automatically called by GetScrap and ReadEdition.  You only need to call
  310. *  this if you need to translated scrap style data, but are not using the ScrapMgr or EditionMgr.
  311. * 
  312. *  Enter:    sourceDataGetter            Pointer to routine that can get src data
  313. *             sourceDataGetterRefCon        Extra parameter for dataGetter
  314. *             destinationFormat            Format of data desired
  315. *             destinationData                Handle in which to store translated data
  316. *             
  317. *  Exit:    dstData                        Handle is resized and filled with data in requested format
  318. */
  319. EXTERN_API( OSErr )
  320. TranslateScrap                    (GetScrapDataUPP         sourceDataGetter,
  321.                                  void *                    sourceDataGetterRefCon,
  322.                                  ScrapType                 destinationFormat,
  323.                                  Handle                 destinationData,
  324.                                  short                     progressDialogID)                    TWOWORDINLINE(0x700E, 0xABFC);
  325.  
  326.  
  327.  
  328.  
  329. #if PRAGMA_STRUCT_ALIGN
  330.     #pragma options align=reset
  331. #elif PRAGMA_STRUCT_PACKPUSH
  332.     #pragma pack(pop)
  333. #elif PRAGMA_STRUCT_PACK
  334.     #pragma pack()
  335. #endif
  336.  
  337. #ifdef PRAGMA_IMPORT_OFF
  338. #pragma import off
  339. #elif PRAGMA_IMPORT
  340. #pragma import reset
  341. #endif
  342.  
  343. #ifdef __cplusplus
  344. }
  345. #endif
  346.  
  347. #endif /* __TRANSLATION__ */
  348.  
  349.